docs: update docs

docs/tariffs.md

@@ -7,6 +7,12 @@
 
 JSON-каталог может содержать несколько тарифов разных моделей: подписки на срок, пакеты трафика без срока действия, разные наборы Internal Squads, лимиты устройств и пакеты докупки. Пример формата: [config/tariffs.example.json](../config/tariffs.example.json).
 
+Коротко по моделям:
+
+- `period` - подписка на срок с месячным лимитом трафика и опциональной докупкой GB поверх месячного лимита;
+- `traffic` - покупка пакетов GB без пользовательского срока действия, где повторная покупка добавляет трафик к текущему остатку;
+- premium-сквады - дополнительный набор Internal Squads внутри любого тарифа, с отдельным названием, счетчиком, месячным лимитом и отдельными пакетами докупки.
+
 ## Управление через админку
 
 Каталог тарифов можно настраивать из Web App админки: раздел **Система → Тарифы**. Админка читает и сохраняет файл из `TARIFFS_CONFIG_PATH`, валидирует данные той же моделью `TariffsConfig`, что и бот, и атомарно перезаписывает JSON только после успешной проверки.
@@ -18,10 +24,14 @@ JSON-каталог может содержать несколько тариф
 - выбор тарифа по умолчанию;
 - настройка `period`-тарифов: месячный лимит, периоды, RUB/Stars цены, пакеты докупки трафика;
 - настройка `traffic`-тарифов: пакеты GB, RUB/Stars цены, курс конвертации;
-- настройка Internal Squads, базового HWID-лимита и пакетов докупки устройств.
+- настройка базовых Internal Squads из списка Remnawave;
+- настройка premium-раздела: названия RU/EN, premium Internal Squads, месячный premium-лимит и RUB/Stars пакеты докупки premium-трафика;
+- настройка базового HWID-лимита и пакетов докупки устройств.
 
 После сохранения изменения применяются к новым запросам Web App сразу, потому что конфиг тарифов загружается из JSON при обращении. Уже созданные подписки сохраняют свой `tariff_key`; при удалении или отключении тарифа проверьте, что активные подписки с этим ключом не требуют дальнейшего продления или смены.
 
+Подробности по админ-панели, правам доступа, сохранению настроек и списку разделов есть в [admin.md](admin.md).
+
 ## Как выбирается режим
 
 Если файл из `TARIFFS_CONFIG_PATH` существует и проходит валидацию, используется каталог тарифов. В этом режиме `TRAFFIC_PACKAGES` и цены подписок из `.env` не формируют витрину продаж, потому что цены и пакеты берутся из JSON.
@@ -46,6 +56,7 @@ JSON-каталог может содержать несколько тариф
       "key": "standard",
       "names": { "ru": "Стандарт", "en": "Standard" },
       "descriptions": { "ru": "Базовый набор серверов" },
+      "premium_names": { "ru": "Premium-серверы", "en": "Premium servers" },
       "squad_uuids": ["uuid-1"],
       "billing_model": "period",
       "monthly_gb": 500,
@@ -71,9 +82,10 @@ JSON-каталог может содержать несколько тариф
 | `tariffs[].descriptions` | Описания тарифа по языкам. |
 | `tariffs[].enabled` | Доступность тарифа на витрине. |
 | `tariffs[].squad_uuids` | Internal Squads Remnawave для пользователей тарифа. |
+| `tariffs[].premium_names` | Название premium-раздела по языкам. Используется в карточке лимита, модалке докупки premium-трафика и предупреждениях. Если поле не задано, используется `Premium-серверы` / `Premium servers`. |
 | `tariffs[].premium_squad_uuids` | Internal Squads с отдельным premium-лимитом. Ноды для учета берутся автоматически из accessible nodes этих сквадов через API панели. |
 | `tariffs[].premium_monthly_gb` | Отдельный месячный лимит трафика по premium-сквадам. `0` или отсутствие поля отключает отдельное ограничение. |
-| `tariffs[].premium_topup_packages` | Пакеты докупки premium-трафика: `{ "gb": 10, "price": 99 }`. |
+| `tariffs[].premium_topup_packages` | Пакеты докупки premium-трафика в формате `{ "rub": [{ "gb": 10, "price": 99 }], "stars": [...] }`. Требуют `premium_squad_uuids`. |
 | `tariffs[].billing_model` | Модель тарифа: `period` или `traffic`. |
 | `tariffs[].hwid_device_limit` | Базовый лимит HWID-устройств. `0` означает безлимит, отсутствие поля использует `USER_HWID_DEVICE_LIMIT`. |
 | `tariffs[].hwid_device_packages` | Пакеты докупки устройств: `{ "count": 1, "price": 99 }`. |
@@ -124,6 +136,7 @@ JSON-каталог может содержать несколько тариф
 ```json
 {
   "squad_uuids": ["standard-squad-uuid"],
+  "premium_names": { "ru": "Premium-серверы", "en": "Premium servers" },
   "premium_squad_uuids": ["premium-squad-uuid"],
   "premium_monthly_gb": 50,
   "premium_topup_packages": {
@@ -144,6 +157,8 @@ JSON-каталог может содержать несколько тариф
 - докупленный premium-трафик не сгорает в конце месяца: каждый месяц сначала расходуется `premium_monthly_gb`, а докупленный остаток уменьшается только на трафик сверх месячного лимита;
 - при новом календарном месяце счетчик premium-трафика и `premium_topup_used_bytes` сбрасываются, но `premium_topup_balance_bytes` переносится дальше.
 
+Если `premium_squad_uuids` заданы, но `premium_monthly_gb` пустой или `0` и нет `premium_topup_packages`, premium-сквады работают как дополнительный доступ без отдельного ограничения. Если заданы `premium_topup_packages` или положительный `premium_monthly_gb`, `premium_squad_uuids` обязательны.
+
 Состояние хранится в подписке:
 
 - `premium_baseline_bytes` - базовый premium-лимит тарифа;
@@ -155,9 +170,11 @@ JSON-каталог может содержать несколько тариф
 
 В пользовательском Web App premium-лимит показывается отдельной карточкой: использовано, лимит, остаток, докупленный переносимый остаток и список серверов/сквадов, на которые действует отдельное ограничение. В Telegram-разделе “Моя подписка” выводится тот же блок.
 
-Предупреждения по premium-лимиту отправляются отдельно от обычного трафика на тех же процентах `TARIFF_TRAFFIC_WARNING_LEVELS`. Сообщение объясняет, что это именно premium-серверы, перечисляет серверы/сквады и ведет пользователя в докупку premium-трафика.
+Обычная докупка и premium-докупка показываются отдельно. Обычная докупка использует `topup_packages` у `period`-тарифа или `traffic_packages` у `traffic`-тарифа. Premium-докупка использует только `premium_topup_packages`, получает `sale_mode=premium_topup` и в заголовке показывает `premium_names`, а не название обычной докупки.
 
-В Web App админке premium-сквады можно выбрать из выпадающего списка. Список берется из API Remnawave, поэтому UUID не нужно копировать вручную.
+Предупреждения по premium-лимиту отправляются отдельно от обычного трафика на тех же процентах `TARIFF_TRAFFIC_WARNING_LEVELS`. Сообщение использует название из `premium_names`, перечисляет серверы/сквады и ведет пользователя в докупку premium-трафика.
+
+В Web App админке premium-сквады можно выбрать из выпадающего списка на вкладке **Premium** в редакторе тарифа. Список берется из API Remnawave (`/api/admin/panel/internal-squads`), поэтому UUID обычно не нужно копировать вручную.
 
 ## Traffic-тарифы