docs: restructure and enhance documentation for Ads and Anonymous Numbers features

docs/client/ads/overview.md

@@ -0,0 +1,16 @@
+# Ads Overview
+
+Ads flow is split into two methods:
+
+- [Top Up TON](topup-ton.md)
+- [Recharge Ads](recharge-ads.md)
+
+Use the first method to send TON to a Telegram user.
+Use the second method to fund your own Telegram Ads account.
+
+## Common errors
+
+- `ConfigurationError`
+- `UserNotFoundError` (for recipient/account issues)
+- `WalletError`
+- `VerificationError`

docs/client/ads/recharge-ads.md

@@ -0,0 +1,23 @@
+# Recharge Ads
+
+Use this method to add funds to your Telegram Ads account.
+
+## Method
+
+```python
+await client.recharge_ads(
+    account: str,
+    amount: int,
+) -> AdsRechargeResult
+```
+
+## Parameters
+
+- `account`: channel or bot username linked to your ads account
+- `amount`: integer from `1` to `1_000_000_000`
+
+**Important:** `amount` must be an integer in the allowed range.
+
+## Return
+
+- `AdsRechargeResult(transaction_id, amount)`

docs/client/ads/topup-ton.md

@@ -0,0 +1,25 @@
+# Top Up TON
+
+Use this method to send TON to a user's Telegram balance.
+
+## Method
+
+```python
+await client.topup_ton(
+    username: str,
+    amount: int,
+    show_sender: bool = True,
+) -> AdsTopupResult
+```
+
+## Parameters
+
+- `username`: recipient Telegram username
+- `amount`: integer from `1` to `1_000_000_000`
+- `show_sender`: controls sender visibility
+
+**Important:** `amount` must be an integer in the allowed range.
+
+## Return
+
+- `AdsTopupResult(transaction_id, username, amount)`