replaced reuse contract errors

[koder-ns]

closes #11

📌 Description

Critical UX & Debugging Issue - The upgrade gate logic currently reuses InvalidAmount, ContractPaused, and InternalError for unrelated upgrade states. This creates dangerous ambiguity during the highest-risk contract operation, making it impossible for clients, operators, and auditors to distinguish between:

• Attempting an upgrade outside the allowed window vs. providing an invalid amount
• Upgrade already running vs. contract being paused
• No upgrade in progress vs. generic internal error

📁 Files Changed

app/contract/contracts/src/errors.rs              - New error types + stable codes
app/contract/contracts/src/admin.rs               - Gate logic updates
app/contract/contracts/src/lib.rs                 - Export new errors
app/contract/contracts/src/upgrade_test.rs        - Comprehensive tests
app/backend/src/common/soroban-errors/upgrade.errors.ts   - Backend mapping
app/backend/src/common/soroban-errors/index.ts    - Export upgrade errors
app/backend/src/__tests__/upgrade.e2e.test.ts     - Integration tests
docs/UPGRADE_ERROR_CODES.md                       - Documentation (NEW)
docs/UPGRADE_STATE_MACHINE.md                     - State machine diagram (NEW)

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@koder-ns's PR #73 was approved and merged by @MaryammAli.

🏆 @koder-ns: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (226 total points). Track your full progress on GrantFox.

👏 Great work, @koder-ns! Keep contributing to BlockDash-Studios.