feat: surface and document per-asset fee configuration

[Mkalbani]

closes #333

Summary

This PR surfaces and fully documents the per-asset fee configuration that was previously declared in storage but not well-documented or easily discoverable.

Changes

📖 Documentation

• README.md: Added comprehensive "Fee Configuration" section explaining:

  • Fee resolution priority (per-asset > oracle > global)
  • Global fee configuration with examples
  • Per-asset fee overrides and use cases
  • Arbiter splits (both legacy and explicit)
  • Collector rotation mechanism
  • Fee breakdown structure

• FEE_CONFIGURATION_GUIDE.md (new): Detailed developer guide covering:

  • All fee configuration patterns with working examples
  • Common use cases (tiered fees, arbiter incentivization, multi-recipient splits, fee-free tokens)
  • FeeRatio validation rules
  • Comprehensive troubleshooting guide

🔧 Code Documentation

• lib.rs: Enhanced docstrings for:

  • set_fee_config() - With priority order and examples
  • set_per_asset_fee() - With fee distribution options and error cases
  • get_per_asset_fee() - With query examples

• admin.rs: Added comprehensive documentation for:

  • set_fee_config() - Fallback priority explanation
  • set_per_asset_fee() - Fee split options, validation, and errors

Problem Solved

Per-asset fee overrides were fully functional but:

• ❌ Not documented at the README level
• ❌ Complex split options unexplained
• ❌ No usage examples or patterns
• ❌ Discovery was difficult for new developers

Solution

✅ Minimal: No code changes (implementation already correct)
✅ Efficient: ~675 lines of documentation vs refactoring
✅ Comprehensive: Multiple documentation levels for different audiences

Files Changed

• README.md - Added fee configuration section
• FEE_CONFIGURATION_GUIDE.md - New comprehensive guide
• contracts/Folder/src/lib.rs - Enhanced entry point docs
• contracts/Folder/src/admin.rs - Enhanced admin function docs

Key Features Now Documented

1. ✅ Per-asset override priority
2. ✅ Global fallback mechanism
3. ✅ Oracle dynamic pricing integration
4. ✅ Legacy arbiter_bps split
5. ✅ Explicit FeeRatio splits with validation
6. ✅ Collector rotation without disruption
7. ✅ Fee breakdown structure
8. ✅ Common patterns with code examples
9. ✅ Troubleshooting guide

Type of Change

• Bug fix
• Documentation
• New feature
• Breaking change

Testing

Documentation quality review only (no code changes).

---

Fixes: Issue #305 (Fee Router v2 - per-asset overrides now fully documented)