feat: settlement V1->V2 migration

[samjay8]

closes #535

Summary

• Adds contracts/settlement/src/migrate.rs -- a storage migration helper that converts V1 (single-token DeveloperBalanceV1) persistent slots to V2 (per-token DeveloperBalance(addr, usdc_token)) slots
• Exposes three admin-gated entry points on CalloraSettlement: migrate_v1_to_v2, migrate_v1_to_v2_page (paginated), and migration_storage_version
• Fixes contracts/settlement/src/types.rs: adds the PendingDeveloperMigration(Address) and StorageVersion variants missing from StorageKey, and adds the AdminMigrationEvent struct (used by admin.rs but previously undefined)
• Fixes contracts/settlement/src/admin.rs: updates balance migration functions to use the two-argument DeveloperBalance(addr, token) key
• Adds docs/MIGRATION.md with a step-by-step migration playbook, pre-migration checklist, merge semantics, rollback plan, and full API reference

Files changed

File	Type	Purpose
contracts/settlement/src/migrate.rs	new	V1->V2 migration logic + 17 tests
contracts/settlement/src/types.rs	modified	Add PendingDeveloperMigration, StorageVersion, AdminMigrationEvent
contracts/settlement/src/admin.rs	modified	Fix DeveloperBalance key arity
contracts/settlement/src/lib.rs	modified	Declare module, expose 3 contract methods
docs/MIGRATION.md	new	Full migration runbook

Design decisions

• Idempotent: re-running completed migration is a no-op
• Merge-safe: V1 and V2 credits merged with checked_add
• Paginated: migrate_v1_to_v2_page caps batch at MAX_BATCH_SIZE (50)
• Overflow-safe: all arithmetic uses checked_add; no unwrap() in production paths
• Require-auth: every state-changing function calls caller.require_auth() and verifies admin

Test plan

• cargo test -p callora-settlement passes (17 new tests in migrate.rs)
• migration_storage_version() returns 1 before and 2 after migration
• V1 balance slots removed; V2 slots carry correct amounts
• Idempotency: calling migration twice does not panic or alter state
• Merge: overlapping V1+V2 balances sum correctly
• Multi-page: 5 developers migrated 2-at-a-time produces correct final balances
• Error cases: non-admin, uninitialized, USDC-unconfigured all panic with correct error code

[drips-wave]

@samjay8 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[GBOYEE]

@GBOYEE has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Implement following existing patterns and conventions. Add tests, ensure CI passes, and document any new API surface.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @GBOYEE to this issue.