Implement billing functionality and enhance role management

- Introduced billing capabilities, allowing users to request payments for subscription periods (3/6/12 months) with admin approval via Telegram.
- Updated role management to include a `BillingEnabled` property, preventing billing for admin roles.
- Enhanced the `CreateRoleCommand` and `UpdateRoleCommand` to accept billing parameters, ensuring proper handling during role creation and updates.
- Added new endpoints for billing management and integrated billing checks into VPN config creation to enforce payment requirements.
- Updated related services, models, and tests to support the new billing features, ensuring comprehensive coverage and functionality.
- Enhanced documentation to reflect the new billing processes and role management changes.

backend/tests/PnvPanel.IntegrationTests/Billing/BillingFlowTests.cs

@@ -0,0 +1,86 @@
+using System.Net;
+using System.Net.Http.Json;
+using PnvPanel.IntegrationTests.TestSupport;
+using Xunit;
+using static PnvPanel.IntegrationTests.TestSupport.AuthTestHelper;
+
+namespace PnvPanel.IntegrationTests.Billing;
+
+[Collection(IntegrationTestCollection.Name)]
+public class BillingFlowTests(PnvPanelWebApplicationFactory factory)
+{
+    private sealed record RoleResponse(Guid Id, string Name, bool BillingEnabled);
+
+    private sealed record ActivationRequestResponse(Guid Id);
+
+    private sealed record BillingStatusResponse(
+        bool BillingEnabled,
+        DateTimeOffset? PaidUntil,
+        bool Suspended,
+        string RequisitesText,
+        object? ActiveRequest
+    );
+
+    /// <summary>
+    /// Проверяет сквозной путь, недоступный unit-тестам (RoleService — Infrastructure/Identity):
+    /// назначение billing-роли автоматически выдаёт грейс-период, и он виден пользователю через
+    /// /api/billing/status.
+    /// </summary>
+    [Fact]
+    public async Task AssigningBillingRole_GrantsGracePeriod_VisibleInBillingStatus()
+    {
+        using var adminClient = factory.CreateClient();
+        var adminToken = await LoginAsAdminAsync(adminClient);
+        adminClient.UseBearerToken(adminToken);
+
+        var createRoleResponse = await adminClient.PostJsonAsync(
+            "/api/admin/roles",
+            new
+            {
+                name = $"billing_{Guid.NewGuid():N}"[..20],
+                maxConfigs = 5,
+                maxIpLimit = -1,
+                billingEnabled = true,
+            }
+        );
+        Assert.Equal(HttpStatusCode.OK, createRoleResponse.StatusCode);
+        var role = await createRoleResponse.ReadAsAsync<RoleResponse>();
+        Assert.True(role!.BillingEnabled);
+
+        using var userClient = factory.CreateClient();
+        var userName = $"bill_{Guid.NewGuid():N}"[..20];
+        var (userId, userToken) = await RegisterAndLoginAsync(userClient, userName, "P@ssw0rd123");
+        userClient.UseBearerToken(userToken);
+
+        var activationRequestResponse = await userClient.PostJsonAsync(
+            "/api/activation/request",
+            new { comment = (string?)null }
+        );
+        var activationRequest =
+            await activationRequestResponse.ReadAsAsync<ActivationRequestResponse>();
+        var approveActivationResponse = await adminClient.PostAsync(
+            $"/api/admin/activation-requests/{activationRequest!.Id}/approve",
+            content: null
+        );
+        Assert.Equal(HttpStatusCode.NoContent, approveActivationResponse.StatusCode);
+
+        var assignRoleResponse = await adminClient.PatchAsJsonAsync(
+            $"/api/admin/users/{userId}/role",
+            new { roleId = role.Id },
+            PnvPanel.IntegrationTests.TestSupport.HttpClientJsonExtensions.JsonOptions
+        );
+        Assert.Equal(HttpStatusCode.NoContent, assignRoleResponse.StatusCode);
+
+        var beforeCheck = DateTimeOffset.UtcNow;
+        var statusResponse = await userClient.GetAsync("/api/billing/status");
+        Assert.Equal(HttpStatusCode.OK, statusResponse.StatusCode);
+        var status = await statusResponse.ReadAsAsync<BillingStatusResponse>();
+
+        Assert.True(status!.BillingEnabled);
+        Assert.False(status.Suspended);
+        Assert.NotNull(status.PaidUntil);
+        // Дефолтный грейс — 7 дней (BillingSettings.DefaultGraceDays), пока админ не настроил своё.
+        Assert.True(status.PaidUntil > beforeCheck.AddDays(6));
+        Assert.True(status.PaidUntil < beforeCheck.AddDays(8));
+    }
+}