docs: add Deduplication v2 migration guide (#333)

[ZohaibHassan16]

Description

This is the final PR for Epic #333. It introduces a comprehensive MIGRATION_V2.md to ensure that our users can easily opt-in to the new performance features.

---

Type of Change

• Documentation update
• New feature (non-breaking change which adds functionality)
• Performance improvement

Related Issues

• Closes [EPIC] Deduplication v2: Higher Accuracy, Lower Latency, Backward Compatible #333 (The Epic)
• Relates to [Sub-Issue 1] Candidate Generation v2 to Cut Pair Explosion #334, [Sub-Issue 2] Two-Stage Scoring: Fast Prefilter + Full Semantic Score #335, [Sub-Issue 3] Semantic Relationship + Triplet Dedup v2 #336

---

Changes Made

• New Migration Guide: Created docs/MIGRATION_V2.md, a detailed guide explaining the "Why" and "How" of the V2 engine.
• Examples: Included specific code examples for enabling:
  • Multi-key blocking and candidate budgeting.
  • Two-stage prefiltering with custom thresholds.
  • Semantic triplet deduplication with synonym mapping.

Testing

• Performed a technical review of the code snippets to ensure they align with the new API implementation in [Sub-Issue 1] Candidate Generation v2 to Cut Pair Explosion #334, [Sub-Issue 2] Two-Stage Scoring: Fast Prefilter + Full Semantic Score #335, and [Sub-Issue 3] Semantic Relationship + Triplet Dedup v2 #336.

---

Definition of Done (Epic #333)

• Legacy mode parity proven: All existing behaviors remain unchanged unless opted-in.
• Performance reports: New mode quality and latency reports attached (see child PRs).
• CI Efficiency: Dedup-heavy CI benchmark time reduced.
• Documentation: Docs and migration notes updated.

[KaifAhmad1]

Status: ✅ APPROVED

Documentation

• ✅ Comprehensive Guide: 152-line migration guide with practical examples
• ✅ Clear Structure: Problem → Solution → Implementation flow
• ✅ Working Code: All examples tested and verified
• ✅ User-Friendly: Step-by-step opt-in instructions

V2 Features

• ✅ Candidate Generation V2: Multi-key blocking, phonetic matching, budgeting
• ✅ Two-Stage Scoring: Fast prefilter with configurable thresholds
• ✅ Semantic Dedup: Synonym mapping, literal normalization
• ✅ API Examples: Both direct and convenience wrapper approaches

Testing

• ✅ Functionality: All V2 features working correctly
• ✅ Performance: 5.86x speedup confirmed (129ms vs 754ms)
• ✅ Integration: Features work together without conflicts
• ✅ Compatibility: Legacy mode preserved as default

Critical Fix

• Infinite Recursion: Fixed self-calling in dedup_triplets()
• Solution: Added name check in registry lookup
• Status: ✅ Fixed and verified working

Epic Completion

• ✅ Epic #333: All requirements satisfied
• ✅ Sub-Issues: #334, #335, #336 integrated and documented
• ✅ Production Ready: Enterprise-grade features with documentation

Files Modified

• docs/MIGRATION_V2.md: +152 lines (comprehensive guide)
• semantica/deduplication/methods.py: +3 lines (recursion fix)
• Implementation files: V2 features working
• Test files: All benchmarks passing

Impact: Completes Deduplication v2 Epic with comprehensive documentation, critical bug fix, and 5.86x performance improvement while maintaining full backward compatibility.