docs: migration map — verified data facts, corrections, import tool

DATA-MIGRATION-MAP.md:
- §10.7 is rewritten from the full dump loaded into MySQL. The legacy
  debt formula is confirmed (1,590/1,591 balances). The earlier claims
  that new_city is a cities5 id, that birthdays are clean and that
  types 3/4/5 are unknown were wrong and are corrected in a table.
  Favourites come from major_favorites, not fav. The role-number clash
  (legacy 86 «حسابدار» vs target 86 «کارشناس فروش») is recorded.
- §10.8 adds the tool's usage, safety rules, test result, and what it
  deliberately does not migrate.
- §11 and §5.5 are brought up to date. The rejected count is 7, not 14.

migration-precheck-3.sql: two bugs that would have failed on the server
are fixed: the reserved word `both` and a collation clash between
cities.title and customers.new_city.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/migration-precheck-3.sql

@@ -23,7 +23,7 @@ SELECT '=== new_city vs city_id ===' AS section;
 
 SELECT
   SUM(new_city IS NOT NULL AND new_city <> '' AND city_id IS     NULL) AS only_new_city,
-  SUM(new_city IS NOT NULL AND new_city <> '' AND city_id IS NOT NULL) AS both,
+  SUM(new_city IS NOT NULL AND new_city <> '' AND city_id IS NOT NULL) AS both_set,
   SUM((new_city IS NULL OR new_city = '')     AND city_id IS NOT NULL) AS only_city_id,
   SUM((new_city IS NULL OR new_city = '')     AND city_id IS     NULL) AS neither
 FROM customers WHERE deleted_at IS NULL;
@@ -32,7 +32,9 @@ FROM customers WHERE deleted_at IS NULL;
 -- اگر بالا باشد، اکثرشان قابل تبدیل به city_id هستند و ستون متنی لازم نیست.
 SELECT 'new_city matches an existing cities.title' AS metric, COUNT(*) AS n
 FROM customers c
-JOIN cities ci ON TRIM(ci.title) = TRIM(c.new_city)
+-- The two columns have different collations (unicode_ci vs general_ci), so
+-- both sides are pinned to one; without it MySQL refuses the comparison.
+JOIN cities ci ON TRIM(ci.title) COLLATE utf8mb4_general_ci = TRIM(c.new_city) COLLATE utf8mb4_general_ci
 WHERE c.deleted_at IS NULL AND c.new_city IS NOT NULL AND c.new_city <> ''
   AND c.city_id IS NULL;