fix(dbml): resolve commented cross-file // Ref: lines

Commented refs are collected per file and resolved against the combined
model after all inputs are loaded (directory, --from-list, merge, jobs).
Matched refs become FKs and relationships; duplicates of existing FKs are
skipped; missing targets are skipped with a warning; column type
mismatches warn.

Also keep reused index names within a DBML table instead of overwriting,
give a second FK to the same table a distinct relationship name, and make
the pgsql writer match relationships to FKs by name first.

pkg/readers/dbml/README.md

@@ -90,11 +90,28 @@ Ref: posts.user_id > users.id [delete: cascade]
 - Default values (`default`)
 - Inline references (`ref`)
 - Standalone `Ref` blocks
+- Commented cross-file refs (`// Ref:` — see below)
 - Indexes and composite indexes
 - Table notes and column notes
 - Enums
 - Dialect directives (`@postgres:` / `@sqlite:` — see below)
 
+## Commented cross-file refs
+
+`// Ref:` / `// ref:` lines (ignored by dbdiagram) become FKs + relationships once both ends are loaded.
+
+| Rule | Behaviour |
+|---|---|
+| When | Single file / directory: end of read. `--from-list`, `merge`, jobs: after all inputs are combined |
+| Match | `schema.table.column` on both sides, case-insensitive |
+| Operators | `>`, `<`, `-` (parsed like `Ref:`) |
+| Duplicate of an FK on the same columns | Skipped silently |
+| Target not loaded | Kept pending; skipped with a warning on the final pass |
+| Column type mismatch | Warning, FK still created (`serial`≈`integer`, `bigserial`≈`bigint`) |
+| Pending state | `Database.Metadata["dbml.commented_refs"]` (`[]string`) |
+
+API: `dbml.ResolveCommentedRefs(db, final bool) []string` returns warnings.
+
 ## Dialect directives
 
 Lines of the form `@<namespace>[(<column>)]: <args>` embed database-specific