feat: add exhaustive currency whitelist validations (#524)

[dannyy2000]

Summary

• Adds explicit admin.require_auth() to add_currency and set_currencies (previously relied on an implicit comment instead of enforced runtime auth)
• Fixes integer overflow in get_whitelisted_currencies_paged: (offset + limit) → offset.saturating_add(limit) to handle u32::MAX inputs safely
• Adds full NatSpec-style doc comments to all CurrencyWhitelist functions (parameters, errors, boundary tables, security notes)
• Expands test_currency.rs with 12 exhaustive boundary test functions covering empty-list, offset/limit saturation, overflow protection, ordering consistency, post-modification pagination, security access, large datasets, concurrent modification simulation, address deduplication, and storage efficiency
• Updates docs/contracts/currency-whitelist.md with authentication model table, security hardening notes, and a full test coverage matrix

Test plan

• src/test_currency.rs compiles with zero errors
• 30 tests covering all add/remove/set/clear flows, admin-only enforcement, invoice/bid rejection, idempotency, and 12 exhaustive pagination boundary cases
• No regressions introduced to currency.rs logic
• Pre-existing failures in unrelated files are unchanged

Closes #524

[drips-wave]

@dannyy2000 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

[dannyy2000]

please merge